home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kplugininfo.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  10.2 KB  |  320 lines
  1. /*  This file is part of the KDE project
  2.     Copyright (C) 2003 Matthias Kretz <kretz@kde.org>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License version 2 as published by the Free Software Foundation.
  7.  
  8.     This library is distributed in the hope that it will be useful,
  9.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.     Library General Public License for more details.
  12.  
  13.     You should have received a copy of the GNU Library General Public License
  14.     along with this library; see the file COPYING.LIB.  If not, write to
  15.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.     Boston, MA 02110-1301, USA.
  17.  
  18. */
  19.  
  20. #ifndef KPLUGININFO_H
  21. #define KPLUGININFO_H
  22.  
  23. #include <qstring.h>
  24. #include <qmap.h>
  25. #include <qstringlist.h>
  26. #include <qvaluelist.h>
  27. #include <kservice.h>
  28.  
  29. class KConfigGroup;
  30.  
  31. /**
  32.  * @ingroup main
  33.  * @ingroup plugin
  34.  * Information about a plugin.
  35.  *
  36.  * This holds all the information about a plugin there is. It's used for the
  37.  * user to decide whether he wants to use this plugin or not.
  38.  *
  39.  * @author Matthias Kretz <kretz@kde.org>
  40.  * @since 3.2
  41.  */
  42. class KUTILS_EXPORT KPluginInfo
  43. {
  44.     public:
  45.         typedef QValueList<KPluginInfo*> List;
  46.  
  47.         /**
  48.          * Read plugin info from @p filename.
  49.          *
  50.          * The file should be of the following form:
  51.          * \verbatim
  52.            [Desktop Entry]
  53.            Name=User Visible Name
  54.            Comment=Description of what the plugin does
  55.  
  56.            [X-KDE Plugin Info]
  57.            Author=Author's Name
  58.            Email=author@foo.bar
  59.            PluginName=internalname
  60.            Version=1.1
  61.            Website=http://www.plugin.org/
  62.            Category=playlist
  63.            Depends=plugin1,plugin3
  64.            License=GPL
  65.            EnabledByDefault=true
  66.            \endverbatim
  67.          * The first two entries in the "Desktop Entry" group always need to
  68.          * be present.
  69.          *
  70.          * The "X-KDE-PluginInfo" keys you may add further entries which
  71.          * will be available using property(). The Website,Category,Require
  72.          * keys are optional.
  73.          * For EnabledByDefault look at isPluginEnabledByDefault.
  74.          *
  75.          * @param filename  The filename of the .desktop file.
  76.          * @param resource  If filename is relative, you need to specify a resource type
  77.          * (e.g. "service", "apps"... KStandardDirs). Otherwise,
  78.          * resource isn't used.
  79.          */
  80.         KPluginInfo( const QString & filename, const char* resource = 0 );
  81.  
  82.         /**
  83.          * Read plugin info from a KService object.
  84.          *
  85.          * The .desktop file should look like this:
  86.          * \verbatim
  87.            [Desktop Entry]
  88.            Encoding=UTF-8
  89.            Icon=mypluginicon
  90.            Type=Service
  91.            ServiceTypes=KPluginInfo
  92.  
  93.            X-KDE-PluginInfo-Author=Author's Name
  94.            X-KDE-PluginInfo-Email=author@foo.bar
  95.            X-KDE-PluginInfo-Name=internalname
  96.            X-KDE-PluginInfo-Version=1.1
  97.            X-KDE-PluginInfo-Website=http://www.plugin.org/
  98.            X-KDE-PluginInfo-Category=playlist
  99.            X-KDE-PluginInfo-Depends=plugin1,plugin3
  100.            X-KDE-PluginInfo-License=GPL
  101.            X-KDE-PluginInfo-EnabledByDefault=true
  102.  
  103.            Name=User Visible Name
  104.            Comment=Description of what the plugin does
  105.            \endverbatim
  106.          * In the first three entries the Icon entry is optional.
  107.          */
  108.         KPluginInfo( const KService::Ptr service );
  109.  
  110. //X         /**
  111. //X          * Create an empty hidden plugin.
  112. //X          * @internal
  113. //X          */
  114. //X         KPluginInfo();
  115.  
  116.         virtual ~KPluginInfo();
  117.  
  118.         /**
  119.          * @return A list of KPluginInfo objects constructed from a list of
  120.          * KService objects. If you get a trader offer of the plugins you want
  121.          * to use you can just pass them to this function.
  122.          */
  123.         static KPluginInfo::List fromServices( const KService::List & services, KConfig * config = 0, const QString & group = QString::null );
  124.  
  125.         /**
  126.          * @return A list of KPluginInfo objects constructed from a list of
  127.          * filenames. If you make a lookup using, for example,
  128.          * KStandardDirs::findAllResources() you pass the list of files to this
  129.          * function.
  130.          */
  131.         static KPluginInfo::List fromFiles( const QStringList & files, KConfig * config = 0, const QString & group = QString::null );
  132.  
  133.         /**
  134.          * @return A list of KPluginInfo objects for the KParts plugins of an
  135.          * instance. You only need the name of the instance not a pointer to the
  136.          * KInstance object.
  137.          */
  138.         static KPluginInfo::List fromKPartsInstanceName( const QString &, KConfig * config = 0, const QString & group = QString::null );
  139.  
  140.         /**
  141.          * @return Whether the plugin should be hidden.
  142.          */
  143.         bool isHidden() const;
  144.  
  145.         /**
  146.          * Set whether the plugin is currently loaded.
  147.          *
  148.          * You might need to reimplement this method for special needs.
  149.          *
  150.          * @see isPluginEnabled()
  151.          * @see save()
  152.          */
  153.         virtual void setPluginEnabled( bool enabled );
  154.  
  155.         /**
  156.          * @return Whether the plugin is currently loaded.
  157.          *
  158.          * You might need to reimplement this method for special needs.
  159.          *
  160.          * @see setPluginEnabled()
  161.          * @see load()
  162.          */
  163.         virtual bool isPluginEnabled() const;
  164.  
  165.         /**
  166.          * @return The default value whether the plugin is enabled or not.
  167.          * Defaults to the value set in the desktop file, or if that isn't set
  168.          * to false.
  169.          */
  170.         bool isPluginEnabledByDefault() const;
  171.  
  172.         /**
  173.          * @return The value associated the the @p key. You can use it if you
  174.          *         want to read custom values. To do this you need to define
  175.          *         your own servicetype and add it to the ServiceTypes keys.
  176.          *
  177.          * @see operator[]
  178.          */
  179.         QVariant property( const QString & key ) const;
  180.  
  181.         /**
  182.          * This is the same as property(). It is provided for convenience.
  183.          *
  184.          * @return The value associated with the @p key.
  185.          *
  186.          * @see property()
  187.          */
  188.         QVariant operator[]( const QString & key ) const;
  189.  
  190.         /**
  191.          * @return The user visible name of the plugin.
  192.          */
  193.         const QString & name() const;
  194.  
  195.         /**
  196.          * @return A comment describing the plugin.
  197.          */
  198.         const QString & comment() const;
  199.  
  200.         /**
  201.          * @return The iconname for this plugin
  202.          */
  203.         const QString & icon() const;
  204.  
  205.         /**
  206.          * @return The file containing the information about the plugin.
  207.          */
  208.         const QString & specfile() const;
  209.  
  210.         /**
  211.          * @return The author of this plugin.
  212.          */
  213.         const QString & author() const;
  214.  
  215.         /**
  216.          * @return The email address of the author.
  217.          */
  218.         const QString & email() const;
  219.  
  220.         /**
  221.          * @return The category of this plugin (e.g. playlist/skin).
  222.          */
  223.         const QString & category() const;
  224.  
  225.         /**
  226.          * @return The internal name of the plugin (for KParts Plugins this is
  227.          * the same name as set in the .rc file).
  228.          */
  229.         const QString & pluginName() const;
  230.  
  231.         /**
  232.          * @return The version of the plugin.
  233.          */
  234.         const QString & version() const;
  235.  
  236.         /**
  237.          * @return The website of the plugin/author.
  238.          */
  239.         const QString & website() const;
  240.  
  241.  
  242.         /**
  243.          * @return The license of this plugin.
  244.          */
  245.         const QString & license() const;
  246.  
  247.         /**
  248.          * @return A list of plugins required for this plugin to be enabled. Use
  249.          *         the pluginName in this list.
  250.          */
  251.         const QStringList & dependencies() const;
  252.  
  253.         /**
  254.          * @return The KService object for this plugin. You might need it if you
  255.          *         want to read custom values. To do this you need to define
  256.          *         your own servicetype and add it to the ServiceTypes keys.
  257.          *         Then you can use the KService::property() method to read your
  258.          *         keys.
  259.          *
  260.          * @see property()
  261.          */
  262.         KService::Ptr service() const;
  263.  
  264.         /**
  265.          * @return A list of Service pointers if the plugin installs one or more
  266.          *         KCModule
  267.          */
  268.         const QValueList<KService::Ptr> & kcmServices() const;
  269.  
  270.         /**
  271.          * Set the KConfigGroup to use for load()ing and save()ing the
  272.          * configuration. This will be overridden by the KConfigGroup passed to
  273.          * save() or load() (if one is passed).
  274.          */
  275.         void setConfig( KConfig * config, const QString & group );
  276.  
  277.         /**
  278.          * @return If the KPluginInfo object has a KConfig object set return
  279.          * it, else return 0.
  280.          */
  281.         KConfig * config() const;
  282.  
  283.         /**
  284.          * @return The groupname used in the KConfig object for load()ing and
  285.          * save()ing whether the plugin is enabled.
  286.          */
  287.         const QString & configgroup() const;
  288.  
  289.         /**
  290.          * Save state of the plugin - enabled or not. This function is provided
  291.          * for reimplementation if you need to save somewhere else.
  292.          * @param config    The KConfigGroup holding the information whether
  293.          *                  plugin is enabled.
  294.          */
  295.         virtual void save( KConfigGroup * config = 0 );
  296.  
  297.         /**
  298.          * Load the state of the plugin - enabled or not. This function is provided
  299.          * for reimplementation if you need to save somewhere else.
  300.          * @param config    The KConfigGroup holding the information whether
  301.          *                  plugin is enabled.
  302.          */
  303.         virtual void load( KConfigGroup * config = 0 );
  304.  
  305.         /**
  306.          * Restore defaults (enabled or not).
  307.          */
  308.         virtual void defaults();
  309.  
  310.     private:
  311.         KPluginInfo( const KPluginInfo & );
  312.         const KPluginInfo & operator=( const KPluginInfo & );
  313.  
  314.         class KPluginInfoPrivate;
  315.         KPluginInfoPrivate * d;
  316. };
  317.  
  318. // vim: sw=4 sts=4 et tw=80
  319. #endif // KPLUGININFO_H
  320.